---
title: Usage
---

## Basic Usage

Once configured, you can simply ask Claude to perform computer tasks:

- "Open Chrome and go to github.com"
- "Create a folder called 'Projects' on my desktop"
- "Find all PDFs in my Downloads folder"
- "Take a screenshot and highlight the error message"

Claude will automatically use your CUA agent to perform these tasks.

## Advanced Features

### Progress Reporting

The MCP server provides real-time progress updates during task execution:

- Task progress is reported as percentages (0-100%)
- Multi-task operations show progress for each individual task
- Progress updates are streamed to the MCP client for real-time feedback

### Error Handling

Robust error handling ensures reliable operation:

- Failed tasks return error messages with screenshots when possible
- Session state is preserved even when individual tasks fail
- Automatic cleanup prevents resource leaks
- Detailed error logging for troubleshooting

### Concurrent Task Execution

For improved performance, multiple tasks can run concurrently:

- Set `concurrent=true` in `run_multi_cua_tasks` for parallel execution
- Each task runs in its own context with isolated state
- Progress tracking works for both sequential and concurrent modes
- Resource pooling ensures efficient computer instance usage

### Session Management

Multi-client support with automatic resource management:

- Each client gets isolated sessions with separate computer instances
- Sessions automatically clean up after 10 minutes of inactivity
- Resource pooling prevents resource exhaustion
- Session statistics available for monitoring

## Target Computer Options

By default, the MCP server runs CUA in a virtual machine for safety. However, you can also configure it to run on your local system.

### Default: Using a VM (Recommended)

The MCP server will automatically start and connect to a VM based on your platform. This is the safest option as AI actions are isolated from your host system.

No additional configuration is needed - this is the default behavior.

### Option: Targeting Your Local Desktop

<Callout type="warn">
  **Warning:** When targeting your local system, AI models have direct access to your desktop and
  may perform risky actions. Use with caution.
</Callout>

To have the MCP server control your local desktop instead of a VM:

1. **Start the Computer Server on your host:**

```bash
pip install cua-computer-server
python -m computer_server
```

2. **Configure the MCP server to use your host system:**

Add the `CUA_USE_HOST_COMPUTER_SERVER` environment variable to your MCP client configuration:

<Tabs items={['Claude Desktop', 'Other MCP Clients']}>
  <Tab value="Claude Desktop">
    Update your Claude Desktop config (see [Installation](/docs/libraries/mcp-server/installation)) to include the environment variable:

    ```json
    {
      "mcpServers": {
        "cua-agent": {
          "command": "/bin/bash",
          "args": ["~/.cua/start_mcp_server.sh"],
          "env": {
            "CUA_MODEL_NAME": "anthropic/claude-3-5-sonnet-20241022",
            "CUA_USE_HOST_COMPUTER_SERVER": "true"
          }
        }
      }
    }
    ```

  </Tab>
  <Tab value="Other MCP Clients">
    Set the environment variable in your MCP client configuration:

    ```bash
    export CUA_USE_HOST_COMPUTER_SERVER=true
    ```

    Then start your MCP client as usual.

  </Tab>
</Tabs>

3. **Restart your MCP client** (e.g., Claude Desktop) to apply the changes.

Now Claude will control your local desktop directly when you ask it to perform computer tasks.

## Usage Examples

### Single Task Execution

```
"Open Safari and navigate to apple.com"
"Create a new folder on the desktop called 'My Projects'"
"Take a screenshot of the current screen"
```

### Multi-Task Execution (Sequential)

```
"Run these tasks in order: 1) Open Finder, 2) Navigate to Documents folder, 3) Create a new folder called 'Work'"
```

### Multi-Task Execution (Concurrent)

```
"Run these tasks simultaneously: 1) Open Chrome, 2) Open Safari, 3) Open Finder"
```

### Session Management

```
"Show me the current session statistics"
"Take a screenshot using session abc123"
"Cleanup session xyz789"
```

### Error Recovery

```
"Try to open a non-existent application and show me the error"
"Find all files with .tmp extension and delete them safely"
```

## First-time Usage Notes

**API Keys**: Ensure you have valid API keys:

- Add your Anthropic API key in the Claude Desktop config (as shown above)
- Or set it as an environment variable in your shell profile
- **Required**: The MCP server needs an API key to authenticate with the model provider

**Model Selection**: Choose the appropriate model for your needs:

- **Claude Sonnet 4**: Latest model with best performance (`anthropic/claude-sonnet-4-20250514`)
- **Claude 3.5 Sonnet**: Reliable performance (`anthropic/claude-3-5-sonnet-20240620`)
- **Computer-Use Preview**: Specialized for computer tasks (`openai/computer-use-preview`)
- **Local Models**: For privacy-sensitive environments
- **Ollama**: For offline usage
